This section describes the structure and principles of writing scripts in ConceptDraw Basic. It contains the following paragraphs:
ConceptDraw supports four execution levels of the ConceptDraw Basic scripting language: Application level, Document level, Page level, Shape level. This means that for any ConceptDraw document or it's page or any shape in the document you can assign a program written in ConceptDraw Basic. Also one can create a program on the entire application level. Any execution level contains at least a built-in module with program code in ConceptDraw Basic.
Execution levels of ConceptDraw Basic are organized in a hierarchy (see the figure below), which reflects how global variables and procedures are inherited from higher levels to the lower ones.
This means, that a script, created for any shape (on the shape
level) also shows all global variables and procedures that belong to higher
levels: Page, Document and Application. In its turn, a page-level script shows
all global variables and procedures of the Document and Application levels.
And finally, a document-level script shows global variables and procedures of
the Application level. Thus, the hierarchy of execution levels determines the
functional purpose of ConceptDraw Basic scripts at different levels.
Application levels script is intended for re-assigning
the behavior of the entire application, and also for defining global variables
and procedures, which may be often used in various documents. For instance,
with the help of interface configuration and an application-level script in
ConceptDraw Basic it's possible to turn ConceptDraw into a specialized application
for computer network designers. One should just write the commonly used routines
(for instance, calculation of the cost of the components) as application-level
scripts and run them using the user-defined menu. Then the user will be able
to automatically calculate the cost of the components for any network diagram.
Document level script is intended for document-specific
calculations and also for defining global variables and procedures, used in
the code of different pages or shapes of the document. For instance, a document-level
script can be used to define specific procedures for creating templates. This
may look like a wizard, that asks questions specific to a certain document type.
Based on the user input, the script can determine the number and size of pages,
create these pages and place necessary shapes on them.
Page level script is intended for calculations and actions,
specific to a certain page of the document, as well as for defining global variables
and procedures, used in the code of the shapes on that page. Scripts at this
level may be used together with document-level scripts when creating templates.
Creating graphic objects (shapes) is slightly easier at the page level, than
at the document level.
Shape level script is intended for calculations, specific
to certain graphic object (shape). For instance, it allows to program an element
of a bar chart in such a way, that it can reflect values from a data base or
an external file. Library shapes can also have scripts.
The code of the scripts of document, page
and shape levels is stored together with the object, to which the script is
assigned. For instance, scripts for the document and its pages and shapes are
stored within the document. For shapes in a library the code is stored with
the library.
An application-level script is stored in a file with
reserved name "AppCDBasicScript.cdb", located in the application data
folder. For example, full path to an external module of the application-level
script on the Windows platform may look like this: "C:\Documents and Settings\Dime1.DIME\Application
Data\CSOdessa\ConceptDraw\AppCDBasicScript.cdb". An application-level script
is only saved if compilation was successful.
ConceptDraw Basic allows to use external modules with
ConceptDraw Basic code by means of the inline command #Include. This
lets create various external libraries of routines.
Source code of ConceptDraw Basic scripts is stored as
text in the UTF-8 encoding, allowing to use string constants and comments in
any language.
For editing and debugging scripts ConceptDraw
has a built-in ConceptDraw Basic script editor. This editor allows to edit scripts
of all execution levels, as well as external modules, connected by the #Include
command. Besides, ConceptDraw Basic script editor lets compile and run scripting
programs at available execution level. The "CDBasic Output" window
serves for debugging and showing warnings and errors.
To edit external modules you can use any other text
editor. However, if the code contains comments or string constant, that include
national characters (non-ANSI symbols), the editor should be able to save text
in the UTF-8 encoding.
A script at any execution level contains
the global execution area, and a set of user procedures, defining local execution
areas.
In the global area global variables are defined, user
procedures are declared and defined, external procedures declared. Also in the
global area is located the code, executed immediately at launch. Variables and
named constants, defined in the global area, can be visible in all user procedures,
defined lower in the code from where they were declared.
Local execution areas contain user procedures. Definitions
of user procedures start with the statements Sub
or Function, and end with End
Sub or End Function respectively. Variables,
defined in a local area, are visible within this area only. This allows to use
local variables and named constants with same names in different procedures.
Any variables is visible down the code from where it
was declared until the end of its visible area.
Below is an example of a ConceptDraw Basic script:
Dim gData(256) As Double ' Declare global variable gData as Double array |
Scripts are executed by the built-in virtual machine of ConceptDraw Basic. The source code in ConceptDraw Basic is first compiled into so called p-code of the virtual machine, which is then executed. So, the life cycle of a program in ConceptDraw Basic can be divided into two stages - compilation and execution.
During compilation the compiler finds
all syntactic errors and informs about them in the "CDBasic Output"
window. Normally (where possible) it displays the error number, short error
description and shows the source module and the line number, in which the error
was found.
When compilation of a script starts, the scripts of
higher execution level are compiled automatically if they weren't compiled earlier.
When writing scripts you should remember that namespaces of variables and procedures
at different levels should not overlap. If variables or procedures were earlier
defined at a higher execution level, this will lead to a compilation error of
"Duplicate definition" type. Also, a compilation error will be caused
by declaring variables or constants with names, coinciding with the names of
the built-in constants or run-time procedures. The same would happen with reserved
words of the ConceptDraw Basic language. Detailed description of compilation
errors can be found in the "Trappable
errors" section.
Successfully compiled code of a ConceptDraw
Basic script can be executed. It can be launched either by the user from the
menu or a toolbar button, or automatically when loading the script-containing
object.
Once a script is launched, scripts of the upper execution
levels are launched automatically if they haven't been launched by the moment
(not resident).
ConceptDraw Basic starts running the script from executing
the statements of the global area. Procedures are skipped at this stage, because
procedures start executed only when they are called. Once the statements of
the global area have been executed, or on executing the Stop
statement, the program goes to the stand-by mode, remaining resident. In this
case any procedure can be called from scripts of lower execution level, or from
the procedures that process reserved events. For instance, a document-level
script can add items to the custom menu of the document and process them by
using its own procedures. Below is an example of such program:
' Definition of procedure
Sub MenuItem1_CmdProc(cmdArgs As String)
Trace "MenuItem1 : " & cmdArgs
' ...
' ...
End Sub
Dim mi As MenuItem
' Enable Document custom menu
thisDoc.CustomMenu.Caption = "My Doc menu"
' Add menu item
set mi = thisDoc.CustomMenu.AddMenuItem(0)
' Set menu item caption
mi.Caption = "Item 1"
mi.OnCmdArgs = "Args string from menu item"
' Set processing procedure
mi.SetCmdProcessing("MenuItem1_CmdProc")
' Suspends execution
Stop
|
On executing the End statement the program stops. All global variables are cleared, and all procedures defined at this level become inaccessible for subsequent calls.
In automatic mode a script is launched
as soon as the object containing it is loaded. That is, an application-level
script is run as soon as the application is launched. After you open a document
or a template, a document-level script is launched. Then, if the document-level
script remains resident, the scripts at all page levels are executed subsequently,
starting from the first page. Once a page-level program has been executed, and
provided it remains resident (i.e. it wasn't stopped by the End
statement), scripts of the shapes on the page are launched. A shape-level script
is also started automatically, once the script-containing object has been inserted
into the document from a library or duplicated.
A flag in the application preferences dialog controls
whether scripts may be launched automatically or not.